🌎 rns.kin.earth git 🌍
docs/source/gettingstartedfast.rst 5de4e24a9f8eec9f615bb3dd7edeb5a808461ccd (5de4e24a) Text, 33.65 KB
Tc9d1d9********************
Tc9d1d9Getting Started Fast
Tc9d1d9********************
The best way to get started with the Reticulum Network Stack depends on what
you want to do. This guide will outline sensible starting paths for different
scenarios.
Tc9d1d9Standalone Reticulum Installation
Tc9d1d9=============================================
If you simply want to install Reticulum and related utilities on a system,
the easiest way is via the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
pip install rns
If you do not already have pip installed, you can install it using the package manager
of your system with a command like Ta5d6ff``Ta5d6ffsudo apt install python3-pipTa5d6ff``,
Ta5d6ff``Ta5d6ffsudo pamac install python-pipTa5d6ff`` or similar.
You can also dowload the Reticulum release wheels from GitHub, or other release channels,
and install them offline using Ta5d6ff``Ta5d6ffpipTa5d6ff``:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
pip install ./rns-1.0.2-py3-none-any.whl
On platforms that limit user package installation via Ta5d6ff``Ta5d6ffpipTa5d6ff``, you may need to manually
allow this using the Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` command line flag when installing. This
will not actually break any packages, unless you have installed Reticulum directly via
your operating system's package manager.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
pip install rns --break-system-packages
For more detailed installation instructions, please see the
Te6edf3:ref:Te6edf3`Platform-Specific Install Notes<install-guides>` section.
After installation is complete, it might be helpful to refer to the
Te6edf3:ref:Te6edf3`Using Reticulum on Your System<using-main>` chapter.
Tc9d1d9Resolving Dependency & Installation Issues
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On some platforms, there may not be binary packages available for all dependencies, and
Ta5d6ff``Ta5d6ffpipTa5d6ff`` installation may fail with an error message. In these cases, the issue can usually
be resolved by installing the development essentials packages for your platform:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Debian / Ubuntu / Derivatives
sudo apt install build-essential
T8b949e# Arch / Manjaro / Derivatives
sudo pamac install base-devel
T8b949e# Fedora
sudo dnf groupinstall Ta5d6ff"Development Tools" Ta5d6ff"Development Libraries"
With the base development packages installed, Ta5d6ff``Ta5d6ffpipTa5d6ff`` should be able to compile any missing
dependencies from source, and complete installation even on platforms that don't have pre-
compiled packages available.
Tc9d1d9Try Using a Reticulum-based Program
Tc9d1d9=============================================
If you simply want to try using a program built with Reticulum, a few different
programs exist that allow basic communication and a range of other useful functions,
even over extremely low-bandwidth Reticulum networks.
These programs will let you get a feel for how Reticulum works. They have been designed
to run well over networks based on LoRa or packet radio, but can also be used over fast
links, such as local WiFi, wired Ethernet, the Internet, or any combination.
As such, it is easy to get started experimenting, without having to set up any radio
transceivers or infrastructure just to try it out. Launching the programs on separate
devices connected to the same WiFi network is enough to get started, and physical
radio interfaces can then be added later.
Tc9d1d9Remote Shell
Tc9d1d9^^^^^^^^^^^^
The Ta5d6ff`rnsh Tffd700<https://github.com/acehoss/rnsh>Ta5d6ff`_ program lets you establish fully interactive
remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
remote system, and is similar to how Ta5d6ff``Ta5d6ffsshTa5d6ff`` works. The Ta5d6ff``Ta5d6ffrnshTa5d6ff`` is very efficient, and
can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
such as LoRa or packet radio.
Tc9d1d9Nomad Network
Tc9d1d9^^^^^^^^^^^^^
The terminal-based program Ta5d6ff`Nomad Network Tffd700<https://github.com/markqvist/nomadnet>Ta5d6ff`_
provides a complete encrypted communications suite built with Reticulum. It features
encrypted messaging (both direct and delayed-delivery for offline users), file sharing,
and has a built-in text-browser and page server with support for dynamically rendered pages,
user authentication and more.
Tb4b4b4.. Tff7b72imageTb4b4b4:: screenshots/nomadnet_3.png
T56d364:target: _images/nomadnet_3.png
Ta5d6ff`Nomad Network Tffd700<https://github.com/markqvist/nomadnet>Ta5d6ff`_ is a user-facing client
for the messaging and information-sharing protocol
Ta5d6ff`LXMF Tffd700<https://github.com/markqvist/lxmf>Ta5d6ff`_, another project built with Reticulum.
You can install Nomad Network via pip:
Tb4b4b4.. Tff7b72codeTb4b4b4::
# Install ...
pip install nomadnet
# ... and run
nomadnet
Tb4b4b4.. Tff7b72noteTb4b4b4::
If this is the very first time you use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install a program
on your system, you might need to reboot your system for your program to become
available. If you get a "command not found" error or similar when running the
program, reboot your system and try again. In some cases, you may even need to
manually add the Ta5d6ff``Ta5d6ffpipTa5d6ff`` install path to your Ta5d6ff``Ta5d6ffPATHTa5d6ff`` environment variable.
Tc9d1d9Sideband
Tc9d1d9^^^^^^^^
If you would rather use a program with a graphical user interface, you can take
a look at Ta5d6ff`Sideband Tffd700<https://unsigned.io/sideband>Ta5d6ff`_, which is available for Android,
Linux, macOS and Windows.
Tb4b4b4.. Tff7b72onlyTb4b4b4:: html
Tb4b4b4 .. Tff7b72imageTb4b4b4:: screenshots/sideband_devices.webp
T56d364:align: center
T56d364:target: _images/sideband_devices.webp
Tb4b4b4.. Tff7b72onlyTb4b4b4:: latex
Tb4b4b4 .. Tff7b72imageTb4b4b4:: screenshots/sideband_devices.png
T56d364:align: center
T56d364:target: _images/sideband_devices.png
Sideband allows you to communicate with other people or LXMF-compatible
systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
Paper Messages, or anything else Reticulum supports. It also interoperates with
the Nomad Network program.
Tc9d1d9MeshChat
Tc9d1d9^^^^^^^^
The Ta5d6ff`Reticulum MeshChat Tffd700<https://github.com/liamcottle/reticulum-meshchat>Ta5d6ff`_ application
is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
page browser and other interesting functionality.
Tb4b4b4.. Tff7b72onlyTb4b4b4:: html
Tb4b4b4 .. Tff7b72imageTb4b4b4:: screenshots/meshchat_1.webp
T56d364:align: center
T56d364:target: _images/meshchat_1.webp
Tb4b4b4.. Tff7b72onlyTb4b4b4:: latex
Tb4b4b4 .. Tff7b72imageTb4b4b4:: screenshots/meshchat_1.png
T56d364:align: center
T56d364:target: _images/meshchat_1.png
Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
any other LXMF client.
Tc9d1d9Using the Included Utilities
Tc9d1d9=============================================
Reticulum comes with a range of included utilities that make it easier to
manage your network, check connectivity and make Reticulum available to other
programs on your system.
You can use Ta5d6ff``Ta5d6ffrnsdTa5d6ff`` to run Reticulum as a background or foreground service,
and the Ta5d6ff``Ta5d6ffrnstatusTa5d6ff``, Ta5d6ff``Ta5d6ffrnpathTa5d6ff`` and Ta5d6ff``Ta5d6ffrnprobeTa5d6ff`` utilities to view and query
network status and connectivity.
To learn more about these utility programs, have a look at the
Te6edf3:ref:Te6edf3`Using Reticulum on Your System<using-main>` chapter of this manual.
Tc9d1d9Creating a Network With Reticulum
Tc9d1d9=============================================
To create a network, you will need to specify one or more *interfaces* for
Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at Ta5d6ff``Ta5d6ff~/.reticulum/configTa5d6ff``. You can get an example
configuration file with all options via Ta5d6ff``Ta5d6ffrnsd --exampleconfigTa5d6ff``.
When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses
your existing Ethernet and WiFi networks (if any), and only allows you to
communicate with other Reticulum peers within your local broadcast domains.
To communicate further, you will have to add one or more interfaces. The default
configuration includes a number of examples, ranging from using TCP over the
internet, to LoRa and Packet Radio interfaces.
With Reticulum, you only need to configure what interfaces you want to communicate
over. There is no need to configure address spaces, subnets, routing tables,
or other things you might be used to from other network types.
Once Reticulum knows which interfaces it should use, it will automatically
discover topography and configure transport of data to any destinations it
knows about.
In situations where you already have an established WiFi or Ethernet network, and
many devices that want to utilise the same external Reticulum network paths (for example over
LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
other device on your local WiFi will then be able to connect to this wider Reticulum
network just using the default (Te6edf3:ref:Te6edf3`AutoInterface<interfaces-auto>`) configuration.
Possibly, the examples in the config file are enough to get you started. If
you want more information, you can read the Te6edf3:ref:Te6edf3`Building Networks<networks-main>`
and Te6edf3:ref:Te6edf3`Interfaces<interfaces-main>` chapters of this manual.
Tc9d1d9Connecting Reticulum Instances Over the Internet
Tc9d1d9================================================
Reticulum currently offers three interfaces suitable for connecting instances over the Internet: Te6edf3:ref:Te6edf3`Backbone<interfaces-backbone>`, Te6edf3:ref:Te6edf3`TCP<interfaces-tcps>`
and Te6edf3:ref:Te6edf3`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum
users should carefully choose the interface which best suites their needs.
The Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using Ta5d6ff``Ta5d6ffI2PInterfaceTa5d6ff``,
however it also leaks more data about the server host.
The Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` is a very fast and efficient interface type available on POSIX operating
systems, designed to handle many hundreds of connections simultaneously with low memory, processing
and I/O overhead. It is fully compatible with the TCP-based interface types.
TCP connections reveal the IP address of both your instance and the server to anyone who can
inspect the connection. Someone could use this information to determine your location or identity. Adversaries
inspecting your packets may be able to record packet metadata like time of transmission and packet size.
Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it.
Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
which most Internet connections don't offer anymore.
The Ta5d6ff``Ta5d6ffI2PInterfaceTa5d6ff`` routes messages through the `Invisible Internet Protocol
(I2P) <https://geti2p.net/en/>`_. To use this interface, users must also run an I2P daemon in
parallel to Ta5d6ff``Ta5d6ffrnsdTa5d6ff``. For always-on I2P nodes it is recommended to use Ta5d6ff`i2pd Tffd700<https://i2pd.website/>Ta5d6ff`_.
By default, I2P will encrypt and mix all traffic sent over the Internet, and
hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
will also relay other I2P user's encrypted packets, which will use extra
bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult.
I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT.
In general it is recommended to use an I2P node if you want to host a publicly accessible
instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.
Tc9d1d9Connect to the Public Testnet
Tc9d1d9===========================================
An experimental public testnet has been made accessible by volunteers in the community. You
can find interface definitions for adding to your Ta5d6ff``Ta5d6ff.reticulum/configTa5d6ff`` file on the
Ta5d6ff`Reticulum Website Tffd700<https://reticulum.network/connect.html>Ta5d6ff`_ or the
Ta5d6ff`Community Wiki Tffd700<https://github.com/markqvist/Reticulum/wiki/Community-Node-List>Ta5d6ff`_
You can connect your devices or instances to one or more of these to gain access to any
Reticulum networks they are physically connected to. Simply add one or more interface
snippets to your config file in the Ta5d6ff``Ta5d6ff[interface]Ta5d6ff`` section, like in the example below:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# TCP/IP interface to the BetweenTheBorders Hub (community-provided)
Tff7b72[[RNS Testnet BetweenTheBorders]]
Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3target_host Tff7b72= Ta5d6ffreticulum.betweentheborders.com
Te6edf3target_port Tff7b72= Ta5d6ff4242
Tb4b4b4.. Tff7b72tipTb4b4b4::
Ideally, set up a Reticulum Transport Node that your own devices can reach locally, and then
connect that transport node to a couple of public entrypoints. This will provide efficient
connections and redundancy in case any of them go down.
Many other Reticulum instances are connecting to this testnet, and you can also join it
via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.
Expect weird things to happen on this network, as people experiment and try out things.
Tb4b4b4.. Tff7b72warningTb4b4b4::
It probably goes without saying, but *don't use the testnet entry-points as
hardcoded or default interfaces in any applications you ship to users*. When
shipping applications, the best practice is to provide your own default
connectivity solutions, if needed and applicable, or in most cases, simply
leave it up to the user which networks to connect to, and how.
Tc9d1d9Hosting Public Entrypoints
Tc9d1d9===========================================
If you want to host a public (or private) entry-point to a Reticulum network over the
Internet, this section offers some helpful pointers. You will need a machine, physical or
virtual with a public IP address, that can be reached by other devices on the Internet.
The most efficient and performant way to host a connectable entry-point supporting many
users is to use the Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff``. This interface type is fully compatible with
the Ta5d6ff``Ta5d6ffTCPClientInterfaceTa5d6ff`` and Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` types, but much faster and uses
less system resources, allowing your device to handle thousands of connections even on
small systems.
It is also important to set your connectable interface to Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` mode, since this
will greatly improve network convergence time and path resolution for anyone connecting
to your entry-point.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a backbone interface
T8b949e# configured for acting as a gateway for users to
T8b949e# connect to either a public or private network
Tff7b72[[Public Gateway]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3mode Tff7b72= Ta5d6ffgateway
Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0
Te6edf3port Tff7b72= Ta5d6ff4242
If instead you want to make a private entry-point from the Internet, you can use the
Te6edf3:ref:Te6edf3`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# A private entry-point requiring a pre-shared
T8b949e# network name and passphrase to connect to.
Tff7b72[[Private Gateway]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3mode Tff7b72= Ta5d6ffgateway
Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0
Te6edf3port Tff7b72= Ta5d6ff4242
Te6edf3network_name Tff7b72= Ta5d6ffprivate_ret
Te6edf3passphrase Tff7b72= Ta5d6ff2owjajquafIanPecAc
If you are hosting an entry-point on an operating system that does not support
Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff``, you can use Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` instead, although it will
not be as performant.
Tc9d1d9Adding Radio Interfaces
Tc9d1d9==============================================
Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. Reticulum supports a wide range of radio
hardware, and if you already have any available, it is very likely that it will
work with Reticulum. For information on how to configure this, see the
Te6edf3:ref:Te6edf3`Interfaces<interfaces-main>` section of this manual.
If you do not already have transceiver hardware available, you can easily and
cheaply build an Te6edf3:ref:Te6edf3`RNode<rnode-main>`, which is a general-purpose long-range
digital radio transceiver, that integrates easily with Reticulum.
To build one yourself requires installing a custom firmware on a supported LoRa
development board with an auto-install script. Please see the Te6edf3:ref:Te6edf3`Communications Hardware<hardware-main>`
chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
Te6edf3:ref:Te6edf3`list of suppliers<rnode-suppliers>`. For more information on RNode, you can also
refer to these additional external resources:
T79c0ff* Ta5d6ff`How To Make Your Own RNodes Tffd700<https://unsigned.io/how-to-make-your-own-rnodes/>Ta5d6ff`_
T79c0ff* Ta5d6ff`Installing RNode Firmware on Compatible LoRa Devices Tffd700<https://unsigned.io/installing-rnode-firmware-on-supported-devices/>Ta5d6ff`_
T79c0ff* Ta5d6ff`Private, Secure and Uncensorable Messaging Over a LoRa Mesh Tffd700<https://unsigned.io/private-messaging-over-lora/>Ta5d6ff`_
T79c0ff* Ta5d6ff`RNode Firmware Tffd700<https://github.com/markqvist/RNode_Firmware/>Ta5d6ff`_
If you have communications hardware that is not already supported by any of the
Te6edf3:ref:Te6edf3`existing interface types<interfaces-main>`, but you think would be suitable for use with Reticulum,
you are welcome to head over to the Ta5d6ff`GitHub discussion pages Tffd700<https://github.com/markqvist/Reticulum/discussions>Ta5d6ff`_
and propose adding an interface for the hardware.
Tc9d1d9Creating and Using Custom Interfaces
Tc9d1d9===========================================
While Reticulum includes a flexible and broad range of built-in interfaces, these
will not cover every conceivable type of communications hardware that Reticulum
can potentially use to communicate.
It is therefore possible to easily write your own interface modules, that can be
loaded at run-time and used on-par with any of the built-in interface types.
For more information on this subject, and code examples to build on, please see
the Te6edf3:ref:Te6edf3`Configuring Interfaces<interfaces-main>` chapter.
Tc9d1d9Develop a Program with Reticulum
Tc9d1d9===========================================
If you want to develop programs that use Reticulum, the easiest way to get
started is to install the latest release of Reticulum via pip:
Tb4b4b4.. Tff7b72codeTb4b4b4::
pip install rns
The above command will install Reticulum and dependencies, and you will be
ready to import and use RNS in your own programs. The next step will most
likely be to look at some Te6edf3:ref:Te6edf3`Example Programs<examples-main>`.
The entire Reticulum API is documented in the Te6edf3:ref:Te6edf3`API Reference<api-main>`
chapter of this manual.
Tc9d1d9Participate in Reticulum Development
Tc9d1d9==============================================
If you want to participate in the development of Reticulum and associated
utilities, you'll want to get the latest source from GitHub. In that case,
don't use pip, but try this recipe:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install dependencies
pip install cryptography pyserial
T8b949e# Clone repository
git clone https://github.com/markqvist/Reticulum.git
T8b949e# Move into Reticulum folder and symlink library to examples folder
Tffa657cd Reticulum
ln -s ../RNS ./Examples/
T8b949e# Run an example
python Examples/Echo.py -s
T8b949e# Unless you've manually created a config file, Reticulum will do so now,
T8b949e# and immediately exit. Make any necessary changes to the file:
nano ~/.reticulum/config
T8b949e# ... and launch the example again.
python Examples/Echo.py -s
T8b949e# You can now repeat the process on another computer,
T8b949e# and run the same example with -h to get command line options.
python Examples/Echo.py -h
T8b949e# Run the example in client mode to "ping" the server.
T8b949e# Replace the hash below with the actual destination hash of your server.
python Examples/Echo.py 174a64852a75682259ad8b921b8bf416
T8b949e# Have a look at another example
python Examples/Filetransfer.py -h
When you have experimented with the basic examples, it's time to go read the
Te6edf3:ref:Te6edf3`Understanding Reticulum<understanding-main>` chapter. Before submitting
your first pull request, it is probably a good idea to introduce yourself on
the Ta5d6ff`disucssion forum on GitHub Tffd700<https://github.com/markqvist/Reticulum/discussions>Ta5d6ff`_,
or ask one of the developers or maintainers for a good place to start.
Tb4b4b4.. Tff7b72_install-guides:
Tc9d1d9Platform-Specific Install Notes
Tc9d1d9==============================================
Some platforms require a slightly different installation procedure, or have
various quirks that are worth being aware of. These are listed here.
Tc9d1d9Android
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^
Reticulum can be used on Android in different ways. The easiest way to get
started is using an app like Ta5d6ff`Sideband Tffd700<https://unsigned.io/sideband>Ta5d6ff`_.
For more control and features, you can use Reticulum and related programs via
the Ta5d6ff`Termux app Tffd700<https://termux.com/>Ta5d6ff`_, at the time of writing available on
Ta5d6ff`F-droid Tffd700<https://f-droid.org>Ta5d6ff`_.
Termux is a terminal emulator and Linux environment for Android based devices,
which includes the ability to use many different programs and libraries,
including Reticulum.
To use Reticulum within the Termux environment, you will need to install
Ta5d6ff``Ta5d6ffpythonTa5d6ff`` and the Ta5d6ff``Ta5d6ffpython-cryptographyTa5d6ff`` library using Ta5d6ff``Ta5d6ffpkgTa5d6ff``, the package-manager
build into Termux. After that, you can use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install Reticulum.
From within Termux, execute the following:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# First, make sure indexes and packages are up to date.
pkg update
pkg upgrade
T8b949e# Then install python and the cryptography library.
pkg install python python-cryptography
T8b949e# Make sure pip is up to date, and install the wheel module.
pip install wheel pip --upgrade
T8b949e# Install Reticulum
pip install rns
If for some reason the Ta5d6ff``Ta5d6ffpython-cryptographyTa5d6ff`` package is not available for
your platform via the Termux package manager, you can attempt to build it
locally on your device using the following command:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# First, make sure indexes and packages are up to date.
pkg update
pkg upgrade
T8b949e# Then install dependencies for the cryptography library.
pkg install python build-essential openssl libffi rust
T8b949e# Make sure pip is up to date, and install the wheel module.
pip install wheel pip --upgrade
T8b949e# To allow the installer to build the cryptography module,
T8b949e# we need to let it know what platform we are compiling for:
Tffa657export Te6edf3CARGO_BUILD_TARGETTff7b72=Ta5d6ff"aarch64-linux-android"
T8b949e# Start the install process for the cryptography module.
T8b949e# Depending on your device, this can take several minutes,
T8b949e# since the module must be compiled locally on your device.
pip install cryptography
T8b949e# If the above installation succeeds, you can now install
T8b949e# Reticulum and any related software
pip install rns
It is also possible to include Reticulum in apps compiled and distributed as
Android APKs. A detailed tutorial and example source code will be included
here at a later point. Until then you can use the Ta5d6ff`Sideband source code Tffd700<https://github.com/markqvist/sideband>Ta5d6ff`_ as an example and starting point.
Tc9d1d9ARM64
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^
On some architectures, including ARM64, not all dependencies have precompiled
binaries. On such systems, you may need to install Ta5d6ff``Ta5d6ffpython3-devTa5d6ff`` (or similar) before
installing Reticulum or programs that depend on Reticulum.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install Python and development packages
sudo apt update
sudo apt install python3 python3-pip python3-dev
T8b949e# Install Reticulum
python3 -m pip install rns
With these packages installed, Ta5d6ff``Ta5d6ffpipTa5d6ff`` will be able to build any missing dependencies
on your system locally.
Tc9d1d9Debian Bookworm
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^
On versions of Debian released after April 2023, it is no longer possible by default
to use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install packages onto your system. Unfortunately, you will need to
use the replacement Ta5d6ff``Ta5d6ffpipxTa5d6ff`` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but will not work
for including and using Reticulum in your own scripts and programs.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install pipx
sudo apt install pipx
T8b949e# Make installed programs available on the command line
pipx ensurepath
T8b949e# Install Reticulum
pipx install rns
Alternatively, you can restore normal behaviour to Ta5d6ff``Ta5d6ffpipTa5d6ff`` by creating or editing
the configuration file located at Ta5d6ff``Ta5d6ff~/.config/pip/pip.confTa5d6ff``, and adding the
following section:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[global]
Te6edf3break-system-packages Tff7b72= Ta5d6fftrue
For a one-shot installation of Reticulum, without globally enabling the Ta5d6ff``Ta5d6ffbreak-system-packagesTa5d6ff``
option, you can use the following command:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
pip install rns --break-system-packages
Tb4b4b4.. Tff7b72noteTb4b4b4::
The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
Tc9d1d9MacOS
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^
To install Reticulum on macOS, you will need to have Python and the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package
manager installed.
Systems running macOS can vary quite widely in whether or not Python is pre-installed,
and if it is, which version is installed, and whether the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager is
also installed and set up. If in doubt, you can Ta5d6ff`download and install Tffd700<https://www.python.org/downloads/>Ta5d6ff`_
Python manually.
When Python and Ta5d6ff``Ta5d6ffpipTa5d6ff`` is available on your system, simply open a terminal window
and use one of the following commands:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install Reticulum and utilities with pip:
pip3 install rns
T8b949e# On some versions, you may need to use the
T8b949e# flag --break-system-packages to install:
pip3 install rns --break-system-packages
Tb4b4b4.. Tff7b72noteTb4b4b4::
The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
Additionally, some version combinations of macOS and Python require you to
manually add your installed Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages directory to your Te6edf3`PATH` environment
variable, before you can use installed commands in your terminal. Usually, adding
the following line to your shell init script (for example Ta5d6ff``Ta5d6ff~/.zshrcTa5d6ff``) will be enough:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
Tffa657export Te6edf3PATHTff7b72=Te6edf3$PATH:~/Library/Python/3.9/bin
Adjust Python version and shell init script location according to your system.
Tc9d1d9OpenWRT
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^
On OpenWRT systems with sufficient storage and memory, you can install
Reticulum and related utilities using the Te6edf3`opkg` package manager and Te6edf3`pip`.
Tb4b4b4.. Tff7b72noteTb4b4b4::
At the time of releasing this manual, work is underway to create pre-built
Reticulum packages for OpenWRT, with full configuration, service
and Ta5d6ff``Ta5d6ffuciTa5d6ff`` integration. Please see the Ta5d6ff`feed-reticulum Tffd700<https://github.com/gretel/feed-reticulum>Ta5d6ff`_
and Ta5d6ff`reticulum-openwrt Tffd700<https://github.com/gretel/reticulum-openwrt>Ta5d6ff`_
repositories for more information.
To install Reticulum on OpenWRT, first log into a command line session, and
then use the following instructions:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install dependencies
opkg install python3 python3-pip python3-cryptography python3-pyserial
T8b949e# Install Reticulum
pip install rns
T8b949e# Start rnsd with debug logging enabled
rnsd -vvv
Tb4b4b4.. Tff7b72noteTb4b4b4::
The above instructions have been verified and tested on OpenWRT 21.02 only.
It is likely that other versions may require slightly altered installation
commands or package names. You will also need enough free space in your
overlay FS, and enough free RAM to actually run Reticulum and any related
programs and utilities.
Depending on your device configuration, you may need to adjust firewall rules
for Reticulum connectivity to and from your device to work. Until proper
packaging is ready, you will also need to manually create a service or startup
script to automatically laucnh Reticulum at boot time.
Please also note that the Te6edf3`AutoInterface` requires link-local IPv6 addresses
to be enabled for any Ethernet and WiFi devices you intend to use. If Ta5d6ff``Ta5d6ffip aTa5d6ff``
shows an address starting with Ta5d6ff``Ta5d6fffe80::Ta5d6ff`` for the device in question,
Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff`` should work for that device.
Tc9d1d9Raspberry Pi
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^
It is currently recommended to use a 64-bit version of the Raspberry Pi OS
if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
don't always have packages available for some dependencies. If Python and the
Te6edf3`pip` package manager is not already installed, do that first, and then
install Reticulum using Te6edf3`pip`.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install dependencies
sudo apt install python3 python3-pip python3-cryptography python3-pyserial
T8b949e# Install Reticulum
pip install rns --break-system-packages
Tb4b4b4.. Tff7b72noteTb4b4b4::
The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
it will require manually configuring and installing required build dependencies,
and is not detailed in this manual.
Tc9d1d9RISC-V
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^
On some architectures, including RISC-V, not all dependencies have precompiled
binaries. On such systems, you may need to install Ta5d6ff``Ta5d6ffpython3-devTa5d6ff`` (or similar) before
installing Reticulum or programs that depend on Reticulum.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install Python and development packages
sudo apt update
sudo apt install python3 python3-pip python3-dev
T8b949e# Install Reticulum
python3 -m pip install rns
With these packages installed, Ta5d6ff``Ta5d6ffpipTa5d6ff`` will be able to build any missing dependencies
on your system locally.
Tc9d1d9Ubuntu Lunar
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^
On versions of Ubuntu released after April 2023, it is no longer possible by default
to use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install packages onto your system. Unfortunately, you will need to
use the replacement Ta5d6ff``Ta5d6ffpipxTa5d6ff`` command instead, which places installed packages in an
isolated environment. This should not negatively affect Reticulum, but will not work
for including and using Reticulum in your own scripts and programs.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
T8b949e# Install pipx
sudo apt install pipx
T8b949e# Make installed programs available on the command line
pipx ensurepath
T8b949e# Install Reticulum
pipx install rns
Alternatively, you can restore normal behaviour to Ta5d6ff``Ta5d6ffpipTa5d6ff`` by creating or editing
the configuration file located at Ta5d6ff``Ta5d6ff~/.config/pip/pip.confTa5d6ff``, and adding the
following section:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72text
[global]
break-system-packages = true
For a one-shot installation of Reticulum, without globally enabling the Ta5d6ff``Ta5d6ffbreak-system-packagesTa5d6ff``
option, you can use the following command:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72text
pip install rns --break-system-packages
Tb4b4b4.. Tff7b72noteTb4b4b4::
The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice
of words. Setting it will of course not break any system packages, but will simply
allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare
cases lead to version conflicts, it does not generally pose any problems, especially
not in the case of installing Reticulum.
Tc9d1d9Windows
Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^
On Windows operating systems, the easiest way to install Reticulum is by using the
Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager from the command line (either the command prompt or Windows
Powershell).
If you don't already have Python installed, Ta5d6ff`download and install Python Tffd700<https://www.python.org/downloads/>Ta5d6ff`_.
At the time of publication of this manual, the recommended version is Ta5d6ff`Python 3.12.7 Tffd700<https://www.python.org/downloads/release/python-3127>Ta5d6ff`_.
**Important!** When asked by the installer, make sure to add the Python program to
your PATH environment variables. If you don't do this, you will not be able to
use the Ta5d6ff``Ta5d6ffpipTa5d6ff`` installer, or run the included Reticulum utility programs (such as
Ta5d6ff``Ta5d6ffrnsdTa5d6ff`` and Ta5d6ff``Ta5d6ffrnstatusTa5d6ff``) from the command line.
After installing Python, open the command prompt or Windows Powershell, and type:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell
pip install rns
You can now use Reticulum and all included utility programs directly from your
preferred command line interface.
Tc9d1d9Pure-Python Reticulum
Tc9d1d9==============================================
Tb4b4b4.. Tff7b72warningTb4b4b4::
If you use the Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package to run Reticulum on systems that
do not support Ta5d6ff`PyCA/cryptography Tffd700<https://github.com/pyca/cryptography>Ta5d6ff`_, it is
important that you read and understand the Te6edf3:ref:Te6edf3`Cryptographic Primitives <understanding-primitives>`
section of this manual.
In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies. In such situations,
you can use the Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package instead of the Ta5d6ff``Ta5d6ffrnsTa5d6ff`` package, or use Ta5d6ff``Ta5d6ffpipTa5d6ff``
with the Ta5d6ff``Ta5d6ff--no-dependenciesTa5d6ff`` command-line option. The Ta5d6ff``Ta5d6ffrnspureTa5d6ff``
package requires no external dependencies for installation. Please note that the
actual contents of the Ta5d6ff``Ta5d6ffrnsTa5d6ff`` and Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` packages are *completely identical*.
The only difference is that the Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package lists no dependencies required
for installation.
No matter how Reticulum is installed and started, it will load external dependencies
only if they are *needed* and *available*. If for example you want to use Reticulum
on a system that cannot support Ta5d6ff``Ta5d6ffpyserialTa5d6ff``, it is perfectly possible to do so using
the Te6edf3`rnspure` package, but Reticulum will not be able to use serial-based interfaces.
All other available modules will still be loaded when needed.
Served by rngit 1.5.0 - Generated in 0.06s